﻿@page "/ru/6.1/modules/plg-elastic-report"
@{
    Layout = "_ArticleLayout";
    ViewBag.Title = "Плагин Гибкий отчёт";
}

@section Styles {
    <link href="~/lib/prismjs/prism.css" rel="stylesheet" />
}

@section Scripts {
    <script src="~/lib/prismjs/prism.js"></script>
}

<nav class="doc-toc">
    <div class="h6">На этой странице</div>
    <hr>
    <ul>
        <li><a href="#overview">Обзор</a></li>
        <li><a href="#installation">Установка</a></li>
        <li>
            <a href="#configuring">Конфигурирование</a>
            <ul>
                <li><a href="#report-form">Форма отчёта</a></li>
                <li><a href="#report-list">Список отчётов</a></li>
                <li><a href="#report-styling">Стили</a></li>
                <li><a href="#report-fonts">Шрифты</a></li>
            </ul>
        </li>
    </ul>
</nav>

<div class="doc-content">
    <h1>Плагин Гибкий отчёт</h1>
    <h2 id="overview">Обзор</h2>
    <p>Плагин Гибкий отчёт позволяет генерировать отчёты в соответствии с пользовательской конфигурацией. С помощью данного плагина Вы можете построить практически любой необходимый отчёт. Пользователю достаточно выбрать период и нажать на кнопку генерации отчёта. Конфигурации отчётов предварительно создаются администратором. Скачать плагин можно по <a href="https://rapidscada.net/store/Module/ru/PlgElasticReport" target="_blank">ссылке</a>.</p>

    <h2 id="installation">Установка</h2>
    <p>Плагин Гибкий отчёт устанавливается по <a href="../installation/install-modules#plugins">инструкции</a>. В ходе установки выполните дополнительное действие: скопируйте файл <code>PlgElasticReport.xml</code> из дистрибутива плагина в свой проект. Файл должен отображаться в проводнике проекта внутри узла <strong>Вебстанция &gt; Конфигурационные файлы</strong>.</p>

    <h2 id="configuring">Конфигурирование</h2>
    <p>Отчёт состоит из секций, которые выводятся в выходной документ одна за другой. Каждая секция имеет свой тип, параметры и привязку к данным. Кроме того, отчёт имеет общие параметры, влияющие на все секции. Один и тот же отчёт может быть сгенерирован в различных форматах. В настоящий момент поддерживаются форматы PDF, Excel и HTML. При этом внешний вид одного и того же отчёта, сгенерированного в разных форматах, может незначительно отличаться.</p>

    <h3 id="report-form">Форма отчёта</h3>
    <p>Для каждой отчётной формы создаётся отдельный файл конфигурации в формате XML. Файл конфигурации задаёт форматирование отчёта и определяет привязку данных отчёта к каналам. Этот файл должен быть сохранён в директории представлений или в её поддиректории внутри проекта.</p>
    <figure class="figure">
        <img src="plg-elastic-report/report-file-ru.png" class="figure-img img-fluid" alt="Файл отчёта" />
    </figure>
    <p>Редактирование файлов конфигурации может осуществляться в любом текстовом редакторе. Например, бесплатный редактор <a href="https://notepad-plus-plus.org/" target="_blank">Notepad++</a> удобен для работы с XML-файлами.</p>
    <p>Пример файла отчёта <code>ElasticReport1.xml</code> содержится в установочном пакете плагина. Данный пример включает подробное описание параметров настройки и демонстрирует формирование секций отчёта всех возможных типов.</p>
    <p>Основные элементы файла конфигурации отчёта:</p>
    <ul>
        <li>Элемент <code>InputOptions</code> содержит настройки входной формы отчёта, с помощью которой пользователь вводит параметры отчёта и запускает формирование документа.</li>
        <li>Элемент <code>OutputOptions</code> содержит настройки форматирования генерируемого документа.</li>
        <li>
            Элемент <code>Document</code> определяет содержимое отчёта.
            <ul>
                <li>Элемент <code>DocumentOptions</code> задаёт основные параметры, относящиеся ко всему документу.</li>
                <li>Элемент <code>Section</code> описывает секцию отчёта, содержащую данные. Отчёт включает одну или несколько секций различных типов.</li>
            </ul>
        </li>
    </ul>
    <p>Поддерживаемые типы секций:</p>
    <ul>
        <li>Секция <code>TimeData</code> отображает данные каналов за выбранный период времени. По горизонтали расположены каналы, по вертикали - временные точки.</li>
        <li>Секция <code>TimeTime</code> отображает данные одного канала в компактной форме. По горизонтали и вертикали расположены временные точки.</li>
        <li>Секция <code>DataData</code> отображает данные в форме таблицы, каждая ячейка которой может быть привязана к своему каналу.</li>
    </ul>
    <p>Плагин позволяет формировать отчёты по историческим данным. Отчёты по текущим данным и событиям не поддерживаются. При выборе исторического архива, на основе которого строится отчёт, рекомендуется отдавать предпочтение архиву с периодом записи данных, совпадающим или близким к шагу секций отчёта. Это позволит избежать выборки лишних данных.</p>

    <h3 id="report-list">Список отчётов</h3>
    <p>Конфигурационный файл <code>PlgElasticReport.xml</code> содержит список отчётов по группам, которые отображаются на странице <strong>Главное меню &gt; Отчёты</strong>. Пример содержимого файла:</p>
    <pre><code class="language-xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot; ?&gt;
&lt;PlgElasticReport&gt;
  &lt;ReportGroup name=&quot;Elastic Reports&quot; isPublic=&quot;false&quot; objNum=&quot;0&quot;&gt;
    &lt;ReportItem reportID=&quot;1&quot; isPublic=&quot;false&quot; objNum=&quot;0&quot; config=&quot;Reports\ElasticReport1.xml&quot; prefix=&quot;MyRep&quot; cnlNums=&quot;&quot;&gt;My report&lt;/ReportItem&gt;
  &lt;/ReportGroup&gt;
&lt;/PlgElasticReport&gt;</code></pre>
    
    <p>
        Атрибуты элемента <code>ReportGroup</code>:<br />
        <code>name</code> - отображаемое наименование группы отчётов;<br />
        <code>isPublic</code> - является ли группа публичной, то есть доступной всем пользователям;<br />
        <code>objNum</code> - номер объекта, к которому относятся отчёты группы. Ограничивает видимость группы в соответствии с правами пользователя на объект.
    </p>
    <p>
        Атрибуты элемента <code>ReportItem</code>:<br />
        <code>reportID</code> - идентификатор отчёта, уникальный в пределах конфигурационного файла;<br />
        <code>isPublic</code> - является ли отчёт публичным, то есть доступным всем пользователям;<br />
        <code>objNum</code> - номер объекта, к которому относится отчёт. Ограничивает доступность отчёта в соответствии с правами пользователя на объект;<br />
        <code>config</code> - путь к файлу конфигурации отчётной формы относительно директории представлений,<br />
        <code>prefix</code> - префикс имени файла, используемый при скачивании отчёта,<br />
        <code>cnlNums</code> - фиксированные номера каналов, по которым строится отчёт.
    </p>

    <h3 id="report-styling">Стили</h3>
    <p>Имеется возможность настроить собственные стили отчётов: шрифты, цвета, размеры ячеек и т.д. Для каждого формата отчётов стили настраиваются отдельно.</p>

    <h4>PDF-стили</h4>
    <p>Файлы <code>PdfStyleDefault.xml</code> и <code>PdfStyleCustom.xml</code> задают форматирование отчётов в формате PDF. Эти файлы расположены в директории веб-приложения <code>ScadaWeb\wwwroot\plugins\ElasticReport\templates</code>. Файл <code>PdfStyleDefault.xml</code> содержит стили по умолчанию и должен оставаться неизменным. Пользовательские стили добавляются в файл <code>PdfStyleCustom.xml</code>. Создавая пользовательские стили, можно наследовать новые стили от существующих или переопределять существующие стили.</p>

    <h4>Excel-стили</h4>
    <p>Аналогично файлы <code>ExcelStyleDefault.xml</code> и <code>ExcelStyleCustom.xml</code>, расположенные в той же директории, задают форматирование отчётов в формате Excel. Файл <code>ExcelStyleDefault.xml</code> содержит стили по умолчанию и должен оставаться неизменным. Пользовательские стили добавляются в файл <code>ExcelStyleCustom.xml</code>. Будьте внимательны, форматы файлов стилей PDF и Excel отличаются.</p>

    <h4>HTML-стили</h4>
    <p>Файлы <code>html-style-default.scss</code> и <code>html-style-custom.css</code> определяют отображение отчётов в формате HTML. Файлы расположены в директории <code>ScadaWeb\wwwroot\plugins\ElasticReport\css</code>. Пользовательские стили добавляются в файл <code>html-style-custom.css</code> по правилам каскадных таблиц стилей (CSS).</p>

    <h3 id="report-fonts">Шрифты</h3>
    <h4>Шрифты в формате PDF</h4>
    <p>При формировании отчётов в формате PDF по умолчанию используется шрифт Arial. Если требуемый шрифт отсутствует в операционной системе, он заменяется на встроенный шрифт Segoe WP. Чтобы изменить шрифт отчётов, необходимо отредактировать файл стилей.</p>
    <p>Поиск шрифта для загрузки происходит по следующему алгоритму:</p>
    <ol>
        <li>Определяется директория поиска. На Windows поиск выполняется в директории <code>C:\Windows\Fonts</code>, на Linux - в директории <code>/usr/share/fonts/truetype</code></li>
        <li>
            На основе имени шрифта (FontFamily) определяются требуемые имена файлов шрифтов.
            <ol type="a">
                <li>Обычный шрифт: <code>FontFamily.ttf</code>, <code>FontFamily-Regular.ttf</code></li>
                <li>Жирный шрифт: <code>FontFamilyb.ttf</code>, <code>FontFamilybd.ttf</code>, <code>FontFamily-Bold.ttf</code></li>
                <li>Наклонный шрифт: <code>FontFamilyi.ttf</code>, <code>FontFamily-Italic.ttf</code>, <code>FontFamily-Oblique.ttf</code></li>
                <li>Жирный и наклонный: <code>FontFamilybi.ttf</code>, <code>FontFamily-BoldItalic.ttf</code>, <code>FontFamily-BoldOblique.ttf</code></li>
            </ol>
        </li>
        <li>Определяются запасные имена файлов шрифтов (кандидаты). Для жирного или наклонного шрифта в качестве кандидатов используются файлы обычного шрифта. Для обычного шрифта запасные варианты отсутствуют.</li>
        <li>Если в директории поиска находится желаемый или запасной шрифт, то файл шрифта загружается и предоставляется для генерации отчёта. Поиск не чувствителен к регистру символов.</li>
    </ol>
    <p>Установленные по умолчанию шрифты обычно не содержат символов таких языков как китайский и корейский. Для формирования отчётов на таких языках рекомендуется установить шрифт <a href="https://learn.microsoft.com/en-us/typography/font-list/arial-unicode-ms" target="_blank">Arial Unicode MS</a>. На Windows установка шрифта должна производиться для всех пользователей, чтобы файл шрифта был помещён в директорию <code>C:\Windows\Fonts</code></p>
    <figure class="figure">
        <img src="plg-elastic-report/install-font-ru.png" class="figure-img img-fluid" alt="Установка шрифта" />
    </figure>

    <h4>Шрифты в формате Excel</h4>
    <p>В генерируемых отчётах в формате Excel указывается только наименование шрифта, сам шрифт не включается в файл отчёта. По умолчанию используется шрифт Arial. При открытии файла с помощью Microsoft Excel или Libre Office Calc шрифт загружается приложением из системы. Если шрифт отсутствует, используется автоматическая замена. Изменить шрифт можно с помощью файла стилей.</p>
</div>
